Welcome to the MacOS Instrumentation System SDK release 1.0.5
What's new in 1.0.5
- This release contains bug fixes in the Instrumentation Viewer. The Instrumentation System User’s Guide and Instrumentation Programmer's Guide have also been slightly modified. The following bugs were fixed:
1400835 - The Instrumentation tree window could be overwritten with viewer pane scrollbars on switching from layout to browser mode.
1616972 - If a multi-part event is logged and the instrumentation data does not contain an end event, the event range duration appears to be an impossibly huge number.
1635134 - The minimum heights for some viewers are too small, causing things like scroll bar thumb overwriting of scroll arrows, etc.
1634541 - The current time text just to the left of the time slider left truncates more than necessary.
What's new in 1.0.4
- This release contains a bug fix release of Instrumentation Viewer. Also, the viewer documentation, Instrumentation Viewer User’s Guide, has been updated to match the current feature set of the viewer. The InstrumentationBackend library, used by the viewer, has also been updated. The following bugs were fixed.
1616981 - Inst. Viewer crashes after setting the "View Data from" popup for a view to "Comparison File", which is "NULL", and then switching to Browse mode.
1613279 - When live data is present and the user opens the Live Data window, the enable/disable column does not accurately reflect the real state of the nodes. It should at least scan through the list when it is opened and mark disabled nodes as disabled.
1619727 - When viewing data live with Instrumentation Viewer, if you change the enable/disable state, then close and reopen the live connection window, the changes are not reflected in the reopened window.
1622392 - Some of the viewers have no text in their viewer options pallette "Viewer Information" display.
1616837 - The names of the viewers should be more consistent. Most names follow the form
<Inst Type> <View Type> Viewer. A few follow the form <View Type> <Inst Type> Viewer.
1616846 - The order of viewers in the Viewer Pallette should be such that the trace viewers are separated from the statistics viewers. Currently, the trace viewers fall in-between various statistics viewers. The trace viewers should probably appear at the top, since the documents tend to address traces before statistics and traces are probably more commonly used than statistics.
1620577 - Small cosmetic problem: the viewer doc window vertical scroll bar is 1 pixel too narrow.
What's new in 1.0.3
- A small window in which access to the instrumentation tree could be improperly synchronized at interrupt time or under MP has been closed. (1600600)
- Some bugs involving clients trying to create trace classes and log traces while the instrumentation library is being initialized have been fixed.
What's new in 1.0.2
- InstLogTraceEventWithData() and InstLogTraceEventWithDataStructure(), which are used to log traces containing user-defined data, can now be called at interrupt time. (1600595)
What's new in 1.0.1
- Missing trace counts are no longer inflated by previous runs of the OneShot Collector. (1402430)
- Calling InstInitialize68K() inside the MPW InstrumentationLib68K.o library now works correctly.
- Remember that if you are updating from 1.0b8 or earlier, you must convert your code to use the renamed identifiers in Instrumentation.h. See the "Interface Thrash" folder for details.
Common questions-and-answers about instrumentation:
• What is instrumentation?
Instrumentation is code that is put into your software in order to produce data at runtime. Examining this data can help you learn more about your program's behavior. You can use this SDK to produce and examine various types of instrumentation data.
• Specifically?
The most common form of instrumentation data is the trace point. A trace point is just a timestamped event. You can define as many different events as you want. Usually, events correspond to function calls.
The other type of data is statistics — mainly counters and histograms.
• How do I use it?
Your software defines and produces the data by calling the Instrumentation Library; the Instrumentation System records it, and the Instrumentation Viewer application displays it.
Instrumentation data is displayed in a time-based format inside user-configured viewer documents. It can also be exported as text for further analysis by other programs.
The most common reason to use instrumentation is to discover where your code is spending its time.
• How do I put instrumentation into my programs?
There is an API to the instrumentation library, including a set of C macros. The most straight-forward way to instrument your program is to add calls that define and produce instrumentation data to your source code.
You can also use the MrPlus tool to add trace instrumentation to your executable without changing your source code. See the “Instrumentation System User’s Guide” for details.
• Where can it go?
Most instrumentation can be defined and produced from any executable — application, driver, MPW tool, what-have-you — at any time, including interrupt time.
• Is it expensive?
Effort has been made to keep the production end of instrumentation light-weight. On a 100MHz 601, logging a trace to an instrumentation point that is in-cache requires 3-4 microseconds; 10-12 microseconds if L2 or TLB cache misses are encountered. Updating other instrumentation has similar costs.
• Do the costs show up in the timings?
No attempt has been made to “factor out” the overhead associated with instrumentation, because the times are absolute times that relate to other events in the system rather than just time differences. Dealing with this is a problem that is under investigation.
In the meantime, the hope is that instrumentation overhead is not a significant part of the runtime, or that where it is it may be discounted “manually.”
• Is it PowerPC-only?
The Instrumentation System will not run on 68K-based Macintoshes. However, 68K code running on a PowerPC-based machine can produce instrumentation data by statically linking against the 68K instrumentation library. The library operates by calling the PowerPC implementation through the Mixed Mode Manager.
• Once I've installed the Instrumentation System, how do I tell if it's working correctly?
1) Launch the InstTest application in the Test Target folder. This will log trace points.
2) Run the OneShot Collector application in the “Instrumentation ƒ” to produce the “Instrumentation Data” file.
3) Double-click the "InstTest view" document inside the Viewer files folder to launch the Instrumentation Viewer.
4) Open the “Instrumentation Data” file inside “Instrumentation ƒ” using the File menu.
This should show you trace data produced by the InstTest application.
(If you launched the Instrumentation Viewer directly, you should ensure that you are in Browse mode. See the Instrumentation Viewer User’s Guide for details.)
• Where do I turn for support?
The first step is to read all of the documentation. (See below.)
If you have further questions, you can post them to the MPW-DEV Internet mailing list. You can get subscription information about this mailing list at <http://www.solutions.apple.com/ListAdmin/>, or send mail to info@solutions.apple.com.
Documentation
This distribution includes the following documentation:
The Instrumentation System User’s Guide. This introduces the Instrumentation System and describes how to install and use it to collect instrumentation data.
The Instrumentation Programmer’s Guide. This describes the client API that is used to provide data to the Instrumentation System.
Sample Code. This consists of several short snippets illustrating how to define and log instrumentation data.
The Instrumentation Viewer User’s Guide. This describes the Instrumentation Viewer, the primary tool for displaying and analyzing instrumentation data.
